package com.zenithmind.document.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.zenithmind.document.pojo.domain.DocumentTag;
import com.zenithmind.document.pojo.query.DocumentTagQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentTagVO;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 文档标签映射器
 * 遵循单一职责原则：专注于文档标签数据访问
 * 遵循依赖倒置原则：定义抽象的数据访问接口
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
@Mapper
public interface DocumentTagMapper extends BaseMapper<DocumentTag> {

    /**
     * 分页查询标签详情
     * 
     * @param page 分页参数
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentTagVO> selectTagPageWithDetails(Page<DocumentTagVO> page, @Param("query") DocumentTagQueryDTO queryDTO);

    /**
     * 根据名称查询标签
     * 
     * @param name 标签名称
     * @return 标签信息
     */
    DocumentTagVO selectTagByName(@Param("name") String name);

    /**
     * 查询所有标签
     * 
     * @return 标签列表
     */
    List<DocumentTagVO> selectAllTags();

    /**
     * 搜索标签
     * 
     * @param keyword 关键词
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> searchTags(@Param("keyword") String keyword, @Param("limit") Integer limit);

    /**
     * 查询热门标签
     * 
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> selectHotTags(@Param("limit") Integer limit);

    /**
     * 查询最新标签
     * 
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> selectLatestTags(@Param("limit") Integer limit);

    /**
     * 查询用户标签
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> selectUserTags(@Param("userId") String userId, @Param("limit") Integer limit);

    /**
     * 查询文档标签
     * 
     * @param documentId 文档ID
     * @return 标签列表
     */
    List<DocumentTagVO> selectDocumentTags(@Param("documentId") String documentId);

    /**
     * 为文档添加标签
     * 
     * @param documentId 文档ID
     * @param tagIds 标签ID列表
     * @param userId 用户ID
     * @return 影响行数
     */
    Integer addTagsToDocument(@Param("documentId") String documentId, @Param("tagIds") List<String> tagIds, @Param("userId") String userId);

    /**
     * 从文档移除标签
     * 
     * @param documentId 文档ID
     * @param tagNames 标签名称列表
     * @return 影响行数
     */
    Integer removeTagsFromDocument(@Param("documentId") String documentId, @Param("tagNames") List<String> tagNames);

    /**
     * 移除文档所有标签
     * 
     * @param documentId 文档ID
     * @return 影响行数
     */
    Integer removeAllTagsFromDocument(@Param("documentId") String documentId);

    /**
     * 批量为文档添加标签
     * 
     * @param documentIds 文档ID列表
     * @param tagIds 标签ID列表
     * @param userId 用户ID
     * @return 影响行数
     */
    Integer batchAddTagsToDocuments(@Param("documentIds") List<String> documentIds, @Param("tagIds") List<String> tagIds, @Param("userId") String userId);

    /**
     * 批量从文档移除标签
     * 
     * @param documentIds 文档ID列表
     * @param tagNames 标签名称列表
     * @return 影响行数
     */
    Integer batchRemoveTagsFromDocuments(@Param("documentIds") List<String> documentIds, @Param("tagNames") List<String> tagNames);

    /**
     * 查询标签使用统计
     * 
     * @param tagId 标签ID
     * @return 统计信息
     */
    Object selectTagUsageStatistics(@Param("tagId") String tagId);

    /**
     * 查询标签云数据
     * 
     * @param limit 限制数量
     * @return 标签云数据
     */
    List<Object> selectTagCloudData(@Param("limit") Integer limit);

    /**
     * 查询相关标签
     * 
     * @param tagId 标签ID
     * @param limit 限制数量
     * @return 相关标签列表
     */
    List<DocumentTagVO> selectRelatedTags(@Param("tagId") String tagId, @Param("limit") Integer limit);

    /**
     * 合并标签
     * 
     * @param sourceTagId 源标签ID
     * @param targetTagId 目标标签ID
     * @return 影响行数
     */
    Integer mergeTags(@Param("sourceTagId") String sourceTagId, @Param("targetTagId") String targetTagId);

    /**
     * 拆分标签
     * 
     * @param tagId 标签ID
     * @param newTagNames 新标签名称列表
     * @return 影响行数
     */
    Integer splitTag(@Param("tagId") String tagId, @Param("newTagNames") List<String> newTagNames);

    /**
     * 重命名标签
     * 
     * @param tagId 标签ID
     * @param newName 新名称
     * @return 影响行数
     */
    Integer renameTag(@Param("tagId") String tagId, @Param("newName") String newName);

    /**
     * 检查标签是否存在
     * 
     * @param name 标签名称
     * @return 是否存在
     */
    Boolean checkTagExists(@Param("name") String name);

    /**
     * 检查标签是否被使用
     * 
     * @param tagId 标签ID
     * @return 是否被使用
     */
    Boolean checkTagInUse(@Param("tagId") String tagId);

    /**
     * 检查标签列表是否被使用
     * 
     * @param tagIds 标签ID列表
     * @return 被使用的标签ID列表
     */
    List<String> checkTagsInUse(@Param("tagIds") List<String> tagIds);

    /**
     * 获取标签建议
     * 
     * @param input 输入文本
     * @param limit 限制数量
     * @return 建议标签列表
     */
    List<String> selectTagSuggestions(@Param("input") String input, @Param("limit") Integer limit);

    /**
     * 查询标签趋势
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 趋势数据
     */
    List<Object> selectTagTrends(@Param("days") Integer days, @Param("limit") Integer limit);

    /**
     * 查询标签分类
     * 
     * @return 标签分类
     */
    List<Object> selectTagCategories();

    /**
     * 设置标签分类
     * 
     * @param tagId 标签ID
     * @param categoryId 分类ID
     * @return 影响行数
     */
    Integer setTagCategory(@Param("tagId") String tagId, @Param("categoryId") String categoryId);

    /**
     * 查询分类下的标签
     * 
     * @param categoryId 分类ID
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> selectTagsByCategory(@Param("categoryId") String categoryId, @Param("limit") Integer limit);

    /**
     * 导出标签数据
     * 
     * @param queryDTO 查询条件
     * @return 导出数据
     */
    Object exportTags(@Param("query") DocumentTagQueryDTO queryDTO);

    /**
     * 批量插入标签
     * 
     * @param tags 标签列表
     * @return 插入数量
     */
    Integer batchInsertTags(@Param("list") List<DocumentTag> tags);

    /**
     * 清理未使用的标签
     * 
     * @return 清理数量
     */
    Integer cleanupUnusedTags();

    /**
     * 同步标签统计
     * 
     * @return 影响行数
     */
    Integer syncTagStatistics();

    /**
     * 查询标签使用历史
     * 
     * @param tagId 标签ID
     * @param limit 限制数量
     * @return 使用历史
     */
    List<Object> selectTagUsageHistory(@Param("tagId") String tagId, @Param("limit") Integer limit);

    /**
     * 查询推荐标签给用户
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 推荐标签列表
     */
    List<DocumentTagVO> selectRecommendedTagsForUser(@Param("userId") String userId, @Param("limit") Integer limit);

    /**
     * 查询标签共现分析
     * 
     * @param tagId 标签ID
     * @param limit 限制数量
     * @return 共现分析数据
     */
    List<Object> selectTagCooccurrenceAnalysis(@Param("tagId") String tagId, @Param("limit") Integer limit);

    /**
     * 查询标签网络图
     * 
     * @param limit 限制数量
     * @return 网络图数据
     */
    Object selectTagNetworkGraph(@Param("limit") Integer limit);

    /**
     * 查询标签聚类
     * 
     * @param clusterCount 聚类数量
     * @return 聚类数据
     */
    List<Object> selectTagClusters(@Param("clusterCount") Integer clusterCount);

    /**
     * 查询标签相似度
     * 
     * @param tagId1 标签1 ID
     * @param tagId2 标签2 ID
     * @return 相似度
     */
    Double selectTagSimilarity(@Param("tagId1") String tagId1, @Param("tagId2") String tagId2);

    /**
     * 查询标签权重
     * 
     * @param documentId 文档ID
     * @return 标签权重数据
     */
    List<Object> selectTagWeights(@Param("documentId") String documentId);

    /**
     * 更新标签权重
     * 
     * @param documentId 文档ID
     * @param tagId 标签ID
     * @param weight 权重
     * @return 影响行数
     */
    Integer updateTagWeight(@Param("documentId") String documentId, @Param("tagId") String tagId, @Param("weight") Double weight);
}
